/**
 * Copyright (c) 2009 Cerner Corporation.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *    Cerner Corporation - initial API and implementation
 */
package com.cerner.system.rest.resource.organizer;

/**
 * API to store, access, navigate, modify and delete resource representations of
 * type {@code E} in a hierarchical tree structure.
 * <ul>
 * <li>ResourceOrganizer&lt;E&gt;.resource(URI).
 * {@link ResourceController#parent() parent()}</li>
 * <li>ResourceOrganizer&lt;E&gt;.resource(URI).{@link ResourceController#get()
 * get()}</li>
 * <li>ResourceOrganizer&lt;E&gt;.resource(URI).
 * {@link ResourceController#put(Object) put(E)}</li>
 * <li>ResourceOrganizer&lt;E&gt;.resource(URI).
 * {@link ResourceController#delete() delete()}</li>
 * </ul>
 * 
 * @author Alex Horn
 * @param <E> class type of resource representation
 */
public interface ResourceOrganizer<E> {

  /**
   * Forces the {@link ResourceOrganizer} to purge any information about
   * previously {@link #resource(java.net.URI) resolved} URIs.
   */
  public void clear();

  /**
   * Dereference the provided URI by {@link java.net.URI#resolve(java.net.URI)
   * resolving} it against the {@link #baseURI()}.
   * 
   * @param uri uniform resource identifier
   * @return controller of the dereferenced resource
   */
  public ResourceController<E> resource(java.net.URI uri);

  /**
   * Obtain the base URI that is used to {@link java.net.URI#resolve(String)
   * resolve} URIs specified in {@link #resource(java.net.URI)}. The base URI
   * must conform to the <a
   * href="http://tools.ietf.org/html/rfc3986#section-4.3">&lt;absolute-URI&gt;
   * syntax rule</a>:
   * 
   * <pre>
   *   scheme &quot;:&quot; hier-part [ &quot;?&quot; query ]
   * </pre>
   * 
   * @return base URI for all relative-path URIs specified in
   *         {@link #resource(java.net.URI)}
   */
  public java.net.URI baseURI();
}
